---
id: checkbox
title: Checkbox
description: A control element that allows for multiple selections within a set.
---

<ComponentPreview id="Checkbox" />

## Anatomy

To set up the checkbox correctly, you'll need to understand its anatomy and how we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="checkbox" />

### Design impact on the asChild property

The `Checkbox.Root` element of the checkbox is a `label` element. This is because the checkbox is a form control and
should be associated with a label to provide context and meaning to the user. Otherwise, the HTML and accessibility
structure will be invalid.

> If you need to use the `asChild` property, make sure that the `label` element is the direct child of the
> `Checkbox.Root` component.

## Examples

Learn how to use the `Checkbox` component in your project. Let's take a look at the most basic example:

<Example id="basic" />

### Controlled

Use the `checked` and `onCheckedChange` props to programatically control the checkbox's state.

<Example id="controlled" />

### Default Checked

Use the `defaultChecked` prop to set the initial checked state in an uncontrolled manner. The checkbox will manage its
own state internally.

<Example id="default-checked" />

### Disabled

Use the `disabled` prop to make the checkbox non-interactive.

<Example id="disabled" />

### Indeterminate

Use the `indeterminate` prop to create a checkbox in an indeterminate state (partially checked).

<Example id="indeterminate" />

### Programmatic Control

Use the `useCheckbox` hook with `setChecked()` to programmatically control the checkbox state.

<Example id="programmatic-control" />

### Access Checkbox state

Use the `Checkbox.Context` and its render prop to access the checkbox's state and methods.

<Example id="render-prop" />

### Field

The checkbox integrates smoothly with the `Field` component to handle form state, helper text, and error text for proper
accessibility.

<Example id="with-field" />

### Form

Pass the `name` and `value` props to the `Checkbox.Root` component to make the checkbox part of a form. The checkbox's
value will be submitted with the form when the user submits it.

<Example id="with-form" />

### Root Provider

Use the `useCheckbox` hook to create the checkbox store and pass it to the `Checkbox.RootProvider` component. This
allows you to have maximum control over the checkbox programmatically.

<Example id="root-provider" />

> If you're using the `Checkbox.RootProvider` component, you don't need to use the `Checkbox.Root` component.

### Group

Use the `Checkbox.Group` component to manage a group of checkboxes. The `Checkbox.Group` component manages the state of
the checkboxes and provides a way to access the checked values.

<Example id="group" />

### Group Controlled

Use the `value` and `onValueChange` props to programmatically control the checkbox group's state. This example
demonstrates how to manage selected checkboxes in an array and display the current selection.

<Example id="group-controlled" />

### Group Provider

Use the `useCheckboxGroup` hook to create the checkbox group store and pass it to the `Checkbox.GroupProvider`
component. This provides maximum control over the group programmatically, similar to how `RootProvider` works for
individual checkboxes.

<Example id="group-provider" />

### Group + Form

Use the `Checkbox.Group` component within a form to handle multiple checkbox values with form submission. The `name`
prop ensures all selected values are collected as an array when the form is submitted using `FormData.getAll()`.

<Example id="group-with-form" />

### Group + Invalid

Use the `invalid` prop on `Checkbox.Group` to mark the entire group as invalid for validation purposes. This applies the
invalid state to all checkboxes within the group.

<Example id="group-with-invalid" />

### Group + Select All

Implement a "select all" checkbox that controls all checkboxes within a group. The parent checkbox automatically shows
an indeterminate state when some (but not all) items are selected, and becomes fully checked when all items are
selected.

<Example id="group-with-select-all" />

### Group + Fieldset

Use the `Fieldset` component with `Checkbox.Group` to provide semantic grouping with legend, helper text, and error text
support.

<Example id="group-with-fieldset" />

## API Reference

### Props

<ComponentTypes id="checkbox" />

### Context

These are the properties available when using `Checkbox.Context`, `useCheckboxContext` hook or `useCheckbox` hook.

<ContextType id="checkbox" />

## Accessibility

Complies with the [Checkbox WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/).

### Keyboard Support

<KeyBindingsTable id="checkbox" />
